A-设备固件升级 | 文档中心

一、内网固件升级-自v6.2.6.x版本起

在内网固件升级中，大致流程如下：

APP 向设备发送升级指令
设备向 APP 查询升级任务信息
APP 向设备返回升级任务信息
设备向 APP 下载升级固件文件
设备升级后向 APP 发送升级结果

注：

其中 APP 向设备发送的指令或信息都是通过任务执行的，所有相关任务可在 [API-Task API](../A-API/A-Task API.md) 中查询
设备向 APP 发送的请求或信息都是以设备事件通知到 APP
设备进行内网升级时，必须是设备内网连接已经成功连接上，可通过xDevice.getLocalConnectionState()==XDevice.State.CONNECTED进行检测

1、APP->设备：发送升级指令

APP 向设备发送升级指令通过XLinkLocalSendTriggerUpgradeTask任务执行

XLinkLocalSendTriggerUpgradeTask task = XLinkLocalSendTriggerUpgradeTask.newBuilder()
        //设置固件升级类型，请参考任务API详细说明
        .setFirmwareType(firmwareType)
        //设置操作的设备对象
        .setCoreDevice(xDevice)
        .setListener(new TaskListenerAdapter<Boolean>() {
            @Override
            public void onComplete(Task<Boolean> task, Boolean result) {
            }
 
            @Override
            public void onError(Task<Boolean> task, Throwable error) {
            }
        })
        .build();
XLinkSDK.startTask(task);

注意事项：该任务返回结果表示指令发送成功，暂不支持确认设备接收到该消息；如发送后设备无响应，应该考虑重试。

2、设备->APP：请求升级任务信息

在设备接收到 APP 发送的升级指令时，设备会向 APP 请求升级任务信息，将通过设备事件的方式将信息发送到 APP。因此使用内网固件升级功能时，必须监听设备事件回调事件进行处理。

configBuilder.setEventListener(new XLinkDeviceEventListener() {
            @Override
            public void onDeviceEventNotify(@NotNull XDevice device, @NotNull List<XLinkDeviceEvent> event, int from) {
                XLinkDeviceEvent devEvent = event.get(0);
                switch (devEvent.type) {
                    case XLinkDeviceEvent.TYPE_FIRMWARE_CHECK_UPGRADE_TASK:
                        //检测升级任务信息
                        FirmwareUpgradeTaskRequest taskRequest = devEvent.parseFrame2DeviceEvent(FirmwareUpgradeTaskRequest.class);
                        break;
                    case XLinkDeviceEvent.TYPE_FIRMWARE_REPORT_UPGRADE_RESULT:
                        //上报升级结果
                        FirmwareReportUpgradeResult result = devEvent.parseFrame2DeviceEvent(FirmwareReportUpgradeResult.class);
                        if (result.isSuccess()) {
                            //获取升级结果信息进行处理
                        }
                        break;
                    case XLinkDeviceEvent.TYPE_FIRMWARE_REPORT_VERSION:
                        //上报固件版本号
                        FirmwareReportVersion version = devEvent.parseFrame2DeviceEvent(FirmwareReportVersion.class);
                        break;
                }
            }
        });

3、APP->设备：返回升级任务信息

APP 首先需要确保从外部获取到有效的固件升级文件，以及该固件相关的版本信息等，这一部分是需要由外部提供的信息。当接收到来自设备的升级任务信息请求的事件时，通过解析出事件可以得到升级任务请求中携带的设备信息。

//解析检测升级任务请求``FirmwareUpgradeTaskRequest taskRequest = devEvent.parseFrame2DeviceEvent(FirmwareUpgradeTaskRequest.``class``);

升级任务请求中包括的信息如下：

字段名	类型	说明
firmwareType	byte	设备当前固件请求查询的固件类型
currentVersion	short	设备当前固件版本号
identifyCode	int	设备当前固件的标识码

根据任务请求中的参数，APP 需要向设备发送升级信息任务。设备升级需要从 APP 下载固件文件，所以 APP 需要提供下载服务器让设备下载固件文件。建议在返回升级任务前启动下载服务器做好下载准备，设备在成功接收到升级任务信息后将会立即进行固件文件下载操作。

XLinkLocalSendUpgradeTaskResultTask task = XLinkLocalSendUpgradeTaskResultTask.newBuilder()
        //通讯的设备对象
        .setCoreDevice(xDevice)
        //任务请求结果码
        .setCode(CoreConstant.FIRMWARE_RESULT_CODE_CHECK_VERSION_SUCCESS)
        //任务ID
        .setTaskId(taskId)
        //固件标识码，该标识码应该与设备请求的标识码一致，如果不一致则设备不会处理此任务
        .setIdentifyCode(identify)
        //固件类型，固件类型应该由提供的固件文件本身决定
        .setFirmwareType(firmwareType)
        //当前的固件版本号，该参数应该来自于设备的当前固件版本号，如果与设备当前固件版本不一致设备不会处理此任务
        .setCurrentVeresion(currentVersion)
        //固件类型的目标版本，即本次提供的固件文件的版本号
        .setTargetVersion((short) firmwareVersion)
        //固件文件的md5值
        .setFileMd5(StringUtil.getBytes(fileMd5))
        //固件文件长度
        .setFileSize(file.length())
        //固件文件下载地址，必须是内网设备可访问到的，并且是完整的下载地址
        .setDownloadUrl(downloadUrl)
        .setListener(new TaskListenerAdapter<Boolean>() {
            @Override
            public void onComplete(Task<Boolean> task, Boolean result) {
            }
 
            @Override
            public void onError(Task<Boolean> task, Throwable error) {
            }
        })
        .build();
XLinkSDK.startTask(task);

发送固件升级任务信息给设备时，需要注意一些参数的设置。

APP 有义务检测并保证固件的有效性，由于内网升级时固件是由 APP 提供的，因此提供的固件的版本号及文件信息等都必须是 APP 提供的。
返回的任务信息中，固件标识码identifyCode与固件当前版本号currentVersion一般是来自于设备事件中的检测任务请求对象FirmwareUpgradeTaskRequest
返回的任务信息中，固件类型firmwareType必须是当前提供的固件类型，而不是根据设备请求的固件类型提供。比如，当提供的固件为 MCU 升级固件时，设备请求的固件类型是 WIFI 类型时，不能提供设备请求信息中的固件类型，这里是真实提供的固件文件的固件类型。一般情况下设备请求的固件类型是取决于发送升级指令时提供的固件类型。
固件文件下载地址必须是设备可访问到的完整的下载地址，如http://127.0.0.1:8080/firmware/file/123456.bin

4、设备->APP：设备返回升级结果

下载流程略。

设备在下载到固件后，校验固件文件正确之后会进行升级，升级后会将升级结果通过设备事件返回给 APP。设备返回升级结果时，并不保证该升级结果必定能接收到。

二、更新说明

日期	更新内容
2019-01-15	初稿，自6.2.6.x版本起

上次更新：2024-05-09